<!DOCTYPE html>
<html id="docs" lang="en" class="">
	<head>
	<meta charset="utf-8">
<title>Documentation Style Guide - Kubernetes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" type="image/png" href="../../../../images/favicon.png">
<link rel="stylesheet" type="text/css" href="../../../../css/base_fonts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/styles.css">
<link rel="stylesheet" type="text/css" href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.css">
<link rel="stylesheet" type="text/css" href="../../../../css/callouts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/custom-jekyll/tags.css">




<meta name="description" content="Documentation Style Guide" />
<meta property="og:description" content="Documentation Style Guide" />

<meta property="og:url" content="https://kubernetes.io/docs/home/contribute/style-guide/" />
<meta property="og:title" content="Documentation Style Guide - Kubernetes" />

<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script
src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU="
crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.js"></script>
<script src="../../../../js/script.js"></script>
<script src="../../../../js/custom-jekyll/tags.js"></script>


	</head>
	<body>
		<div id="cellophane" onclick="kub.toggleMenu()"></div>

<header>
    <a href="../../../../index.html" class="logo"></a>

    <div class="nav-buttons" data-auto-burger="primary">
        <ul class="global-nav">
            
            
            <li><a href="../../../home.1">Documentation</a></li>
            
            <li><a href="../../../../blog/index.html">Blog</a></li>
            
            <li><a href="../../../../partners/index.html">Partners</a></li>
            
            <li><a href="../../../../community/index.html">Community</a></li>
            
            <li><a href="../../../../case-studies/index.html">Case Studies</a></li>
            
            
             <li>
                <a href="../style-guide.1#">
                    English <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="../../../../zh/index.html">中文 Chinese</a></li>
                
                    <li><a href="../../../../ko/index.html">한국어 Korean</a></li>
                
                </ul>
            </li>
         
            <li>
                <a href="../style-guide.1#">
                    v1.11 <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="https://kubernetes.io">v1.12</a></li>
                
                    <li><a href="../../../../index.html">v1.11</a></li>
                
                    <li><a href="https://v1-10.docs.kubernetes.io">v1.10</a></li>
                
                    <li><a href="https://v1-9.docs.kubernetes.io">v1.9</a></li>
                
                </ul>
            </li>
        </ul>
        
        <a href="../../../tutorials/kubernetes-basics/index.html" class="button" id="tryKubernetes" data-auto-burger-exclude>Try Kubernetes</a>
        <button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
    </div>

    <nav id="mainNav">
        <main data-auto-burger="primary">
        <div class="nav-box">
            <h3><a href="../../../tutorials/stateless-application/hello-minikube/index.html">Get Started</a></h3>
            <p>Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../home.1">Documentation</a></h3>
            <p>Learn how to use Kubernetes with the use of walkthroughs, samples, and reference documentation. You can even <a href="../../../../editdocs/index.html" data-auto-burger-exclude>help contribute to the docs</a>!</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../community/index.html">Community</a></h3>
            <p>If you need help, you can connect with other Kubernetes users and the Kubernetes authors, attend community events, and watch video presentations from around the web.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../blog/index.html">Blog</a></h3>
            <p>Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.</p>
        </div>
        </main>
        <main data-auto-burger="primary">
        <div class="left">
            <h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
            <a href="https://github.com/kubernetes/kubernetes" class="button" data-auto-burger-exclude>View On Github</a>
        </div>

        <div class="right">
            <h5 class="github-invite">Explore the community</h5>
            <div class="social">
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>Twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
        </div>
        <div class="clear" style="clear: both"></div>
        </main>
    </nav>
</header>

		
		
		<section id="hero" class="light-text no-sub">
			





<h1></h1>
<h5></h5>












<div id="vendorStrip" class="light-text">
	<ul>
		
		
		<li><a href="../../../home.1" class="YAH">DOCUMENTATION</a></li>
		
		
		<li><a href="../../../setup/index.html">SETUP</a></li>
		
		
		<li><a href="../../../concepts/index.html">CONCEPTS</a></li>
		
		
		<li><a href="../../../tasks/index.html">TASKS</a></li>
		
		
		<li><a href="../../../tutorials/index.html">TUTORIALS</a></li>
		
		
		<li><a href="../../../reference.1">REFERENCE</a></li>
		
	</ul>
	<div id="searchBox">
		<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)" autofocus="autofocus">
	</div>
</div>

		</section>
		
		
<section id="deprecationWarning">
  <main>
    <div class="content deprecation-warning">
      <h3>
        Documentation for Kubernetes v1.11 is no longer actively maintained. The version you are currently viewing is a static snapshot.
        For up-to-date documentation, see the <a href="https://kubernetes.io/docs/home/">latest</a> version.
      </h3>
    </div>
  </main>
</section>


		<section id="encyclopedia">
			
<div id="docsToc">
     <div class="pi-accordion">
    	
        
        
        
        
        
         
             
                 
                          
                          
                 
             
         
             
         
             
         
             
         
             
         
             
         
             
         
             
         
         
        
        <a class="item" data-title="Documentation" href="../../../home.1"></a>

	
	
		
		
	<div class="item" data-title="Contributing to the Kubernetes Docs">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Content Organization" href="../content-organization/index.html"></a>

		
	
		
		
<a class="item" data-title="Creating a Documentation Pull Request" href="../stage-documentation-changes/index.html"></a>

		
	
		
		
<a class="item" data-title="Custom Hugo Shortcodes" href="../includes.1"></a>

		
	
		
		
<a class="item" data-title="Documentation Style Guide" href="../style-guide.1"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for Kubernetes Federation API" href="../generated-reference/federation-api/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for kubectl Commands" href="../generated-reference/kubectl/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for the Kubernetes API" href="../generated-reference/kubernetes-api/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Pages for Kubernetes Components and Tools" href="../generated-reference/kubernetes-components/index.html"></a>

		
	
		
		
<a class="item" data-title="Localizing Kubernetes Documentation" href="../localization/index.html"></a>

		
	
		
		
<a class="item" data-title="Participating in SIG-DOCS" href="../participating/index.html"></a>

		
	
		
		
<a class="item" data-title="Reviewing Documentation Issues" href="../review-issues/index.html"></a>

		
	
		
		
<a class="item" data-title="Using Page Templates" href="../page-templates/index.html"></a>

		
	
		
		
<a class="item" data-title="Writing a Blog Post" href="../blog-post/index.html"></a>

		
	
		
		
<a class="item" data-title="Writing a New Topic" href="../write-new-topic/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
<a class="item" data-title="Supported Versions of the Kubernetes Documentation" href="../../supported-doc-versions/index.html"></a>

		
	






     </div> 
    <button class="push-menu-close-button" onclick="kub.toggleToc()"></button>
</div> 

			<div id="docsContent">
				
<p><a href="../../../editdocs#docs/home/contribute/style-guide.md" id="editPageButton">Edit This Page</a></p>

<h1>Documentation Style Guide</h1>



<p>This page gives writing style guidelines for the Kubernetes documentation.
These are guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.</p>

<p>For additional information on creating new content for the Kubernetes
docs, follow the instructions on
<a href="../page-templates/index.html">using page templates</a> and
<a href="../stage-documentation-changes/index.html">creating a documentation pull request</a>.</p>









<ul id="markdown-toc">










<li><a href="../style-guide.1#language">Language</a></li>




<li><a href="../style-guide.1#documentation-formatting-standards">Documentation formatting standards</a></li>




<li><a href="../style-guide.1#inline-code-formatting">Inline code formatting</a></li>




<li><a href="../style-guide.1#code-snippet-formatting">Code snippet formatting</a></li>




<li><a href="../style-guide.1#kubernetes-io-word-list">Kubernetes.io word list</a></li>




<li><a href="../style-guide.1#shortcodes">Shortcodes</a></li>




<li><a href="../style-guide.1#common-shortcode-issues">Common Shortcode Issues</a></li>




<li><a href="../style-guide.1#content-best-practices">Content best practices</a></li>




<li><a href="../style-guide.1#patterns-to-avoid">Patterns to avoid</a></li>




















<li><a href="../style-guide.1#what-s-next">What's next</a></li>



</ul>


<blockquote class="note">
  <div><strong>Note:</strong> Kubernetes documentation uses <a href="https://github.com/russross/blackfriday" target="_blank">Blackfriday Markdown Renderer</a> along with a few <a href="../includes.1">Hugo Shortcodes</a> to support glossary entries, tabs, and representing feature state.</div>
</blockquote>

<h2 id="language">Language</h2>

<p>Kubernetes documentation uses US English.</p>

<h2 id="documentation-formatting-standards">Documentation formatting standards</h2>

<h3 id="use-camel-case-for-api-objects">Use camel case for API objects</h3>

<p>When you refer to an API object, use the same uppercase and lowercase letters
that are used in the actual object name. Typically, the names of API
objects use
<a href="https://en.wikipedia.org/wiki/Camel_case" target="_blank">camel case</a>.</p>

<p>Don&rsquo;t split the API object name into separate words. For example, use
PodTemplateList, not Pod Template List.</p>

<p>Refer to API objects without saying &ldquo;object,&rdquo; unless omitting &ldquo;object&rdquo;
leads to an awkward construction.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
  <tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
  <tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
  <tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
  <tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
</table>

<h3 id="use-angle-brackets-for-placeholders">Use angle brackets for placeholders</h3>

<p>Use angle brackets for placeholders. Tell the reader what a placeholder
represents.</p>

<ol>
<li><p>Display information about a pod:</p>

<p>kubectl describe pod <pod-name></p>

<p>where <code>&lt;pod-name&gt;</code> is the name of one of your pods.</p></li>
</ol>

<h3 id="use-bold-for-user-interface-elements">Use bold for user interface elements</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
  <tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
</table>

<h3 id="use-italics-to-define-or-introduce-new-terms">Use italics to define or introduce new terms</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
  <tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
</table>

<h3 id="use-code-style-for-filenames-directories-and-paths">Use code style for filenames, directories, and paths</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
  <tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
  <tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
</table>

<h3 id="use-the-international-standard-for-punctuation-inside-quotes">Use the international standard for punctuation inside quotes</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
  <tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
</table>

<h2 id="inline-code-formatting">Inline code formatting</h2>

<h3 id="use-code-style-for-inline-code-and-commands">Use code style for inline code and commands</h3>

<p>For inline code in an HTML document, use the <code>&lt;code&gt;</code> tag. In a Markdown
document, use the backtick (`).</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
  <tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
</table>

<h3 id="use-code-style-for-object-field-names">Use code style for object field names</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
  <tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
</table>

<h3 id="use-normal-style-for-string-and-integer-field-values">Use normal style for string and integer field values</h3>

<p>For field values of type string or integer, use normal style without quotation marks.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
  <tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
  <tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
</table>

<h2 id="code-snippet-formatting">Code snippet formatting</h2>

<h3 id="don-t-include-the-command-prompt">Don&rsquo;t include the command prompt</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
</table>

<h3 id="separate-commands-from-output">Separate commands from output</h3>

<p>Verify that the pod is running on your chosen node:</p>

<pre><code>kubectl get pods --output=wide
</code></pre>

<p>The output is similar to this:</p>

<pre><code>NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0
</code></pre>

<h3 id="versioning-kubernetes-examples">Versioning Kubernetes examples</h3>

<p>Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the <strong>Before you begin</strong> section.</p>

<p>To specify the Kubernetes version for a task or tutorial page, include <code>min-kubernetes-server-version</code> in the front matter of the page.</p>

<p>If the example YAML is in a standalone file, find and review the topics that include it as a reference.
Verify that any topics using the standalone YAML have the appropriate version information defined.
If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.</p>

<p>For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">---<span style="color:#bbb">
</span><span style="color:#bbb"></span>title:<span style="color:#bbb"> </span>&lt;your<span style="color:#bbb"> </span>tutorial<span style="color:#bbb"> </span>title<span style="color:#bbb"> </span>here<span style="color:#b44;font-style:italic">&gt;
</span><span style="color:#b44;font-style:italic">min-kubernetes-server-version: v1.8
</span><span style="color:#b44;font-style:italic">---</span></code></pre></div>
<p>In code and configuration examples, do not include comments about alternative versions.
Be careful to not include incorrect statements in your examples as comments, such as:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">apiVersion:<span style="color:#bbb"> </span>v1<span style="color:#bbb"> </span><span style="color:#080;font-style:italic"># earlier versions use...</span><span style="color:#bbb">
</span><span style="color:#bbb"></span>kind:<span style="color:#bbb"> </span>Pod<span style="color:#bbb">
</span><span style="color:#bbb"></span>...</code></pre></div>
<h2 id="kubernetes-io-word-list">Kubernetes.io word list</h2>

<p>A list of Kubernetes-specific terms and words to be used consistently across the site.</p>

<table>
  <tr><th>Term</th><th>Usage</th></tr>
  <tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
  <tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
  <tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
</table>

<h2 id="shortcodes">Shortcodes</h2>

<p>Hugo <a href="https://gohugo.io/content-management/shortcodes" target="_blank">Shortcodes</a> help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: <strong>Note:</strong> {{&lt; note &gt;}}, <strong>Caution:</strong> {{&lt; caution &gt;}}, and <strong>Warning:</strong> {{&lt; warning &gt;}}.</p>

<ol>
<li><p>Surround the text with an opening and closing shortcode.</p></li>

<li><p>Use the following syntax to apply a style:</p>

<pre><code>{{&lt; note &gt;}}
**Note:** The prefix you use is the same text you use in the tag.
{{&lt; /note &gt;}}
</code></pre></li>
</ol>

<p>The output is:</p>

<blockquote class="note">
  <div><strong>Note:</strong> The prefix you choose is the same text for the tag.</div>
</blockquote>

<h3 id="note">Note</h3>

<p>Use {{&lt; note &gt;}} to highlight a tip or a piece of information that may be helpful to know.</p>

<p>For example:</p>

<pre><code>{{&lt; note &gt;}}
**Note:** You can _still_ use Markdown inside these callouts.
{{&lt; /note &gt;}}
</code></pre>

<p>The output is:</p>

<blockquote class="note">
  <div><strong>Note:</strong> You can <em>still</em> use Markdown inside these callouts.</div>
</blockquote>

<h3 id="caution">Caution</h3>

<p>Use {{&lt; caution &gt;}} to call attention to an important piece of information to avoid pitfalls.</p>

<p>For example:</p>

<pre><code>{{&lt; caution &gt;}}
**Caution:** The callout style only applies to the line directly above the tag.
{{&lt; /caution &gt;}}
</code></pre>

<p>The output is:</p>

<blockquote class="caution">
  <div><strong>Caution:</strong> The callout style only applies to the line directly above the tag.</div>
</blockquote>

<h3 id="warning">Warning</h3>

<p>Use {{&lt; warning &gt;}} to indicate danger or a piece of information that is crucial to follow.</p>

<p>For example:</p>

<pre><code>{{&lt; warning &gt;}}
**Warning:** Beware.
{{&lt; /warning &gt;}}
</code></pre>

<p>The output is:</p>

<blockquote class="warning">
  <div><strong>Warning:</strong> Beware.</div>
</blockquote>

<h2 id="common-shortcode-issues">Common Shortcode Issues</h2>

<h3 id="ordered-lists">Ordered Lists</h3>

<p>Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag.</p>

<p>For example:</p>

<pre><code>1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   {{&lt; note &gt;}}**Note:** Grease the pan for best results.{{&lt; /note &gt;}}

1. Bake for 20-25 minutes or until set.
</code></pre>

<p>The output is:</p>

<ol>
<li><p>Preheat oven to 350˚F</p></li>

<li><p>Prepare the batter, and pour into springform pan.
<blockquote class="note">
<div><strong>Note:</strong> Grease the pan for best results.</div>
</blockquote></p></li>

<li><p>Bake for 20-25 minutes or until set.</p></li>
</ol>

<h2 id="content-best-practices">Content best practices</h2>

<p>This section contains suggested best practices for clear, concise, and consistent content.</p>

<h3 id="use-present-tense">Use present tense</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
</table>

<p>Exception: Use future or past tense if it is required to convey the correct
meaning.</p>

<h3 id="use-active-voice">Use active voice</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
  <tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
</table>

<p>Exception: Use passive voice if active voice leads to an awkward construction.</p>

<h3 id="use-simple-and-direct-language">Use simple and direct language</h3>

<p>Use simple and direct language. Avoid using unnecessary phrases, such as saying &ldquo;please.&rdquo;</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
  <tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
  <tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>

</table>

<h3 id="address-the-reader-as-you">Address the reader as &ldquo;you&rdquo;</h3>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
    <tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
</table>

<h3 id="avoid-latin-phrases">Avoid Latin phrases</h3>

<p>Prefer English terms over Latin abbreviations.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>For example, ...</td><td>e.g., ...</td></tr>
  <tr><td>That is, ...</td><td>i.e., ...</td></tr>
</table>

<p>Exception: Use &ldquo;etc.&rdquo; for et cetera.</p>

<h2 id="patterns-to-avoid">Patterns to avoid</h2>

<h3 id="avoid-using-we">Avoid using &ldquo;we&rdquo;</h3>

<p>Using &ldquo;we&rdquo; in a sentence can be confusing, because the reader might not know
whether they&rsquo;re part of the &ldquo;we&rdquo; you&rsquo;re describing.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
  <tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
  <tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
</table>

<h3 id="avoid-jargon-and-idioms">Avoid jargon and idioms</h3>

<p>Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
    <tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
</table>

<h3 id="avoid-statements-about-the-future">Avoid statements about the future</h3>

<p>Avoid making promises or giving hints about the future. If you need to talk about
an alpha feature, put the text under a heading that identifies it as alpha
information.</p>

<h3 id="avoid-statements-that-will-soon-be-out-of-date">Avoid statements that will soon be out of date</h3>

<p>Avoid words like &ldquo;currently&rdquo; and &ldquo;new.&rdquo; A feature that is new today might not be
considered new in a few months.</p>

<table>
  <tr><th>Do</th><th>Don't</th></tr>
  <tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
    <tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
</table>












<h2 id="what-s-next">What&#39;s next</h2>
<ul>
<li>Learn about <a href="../write-new-topic/index.html">writing a new topic</a>.</li>
<li>Learn about <a href="../page-templates/index.html">using page templates</a>.</li>
<li>Learn about <a href="../stage-documentation-changes/index.html">staging your changes</a></li>
<li>Learn about <a href="../stage-documentation-changes/index.html">creating a pull request</a>.</li>
</ul>






				<div class="issue-button-container">
					<p><a href="../style-guide.1"><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/home/contribute/style-guide.md?pixel" alt="Analytics" /></a></p>
					
					
					<script type="text/javascript">
					PDRTJS_settings_8345992 = {
					"id" : "8345992",
					"unique_id" : "\/docs\/home\/contribute\/style-guide\/",
					"title" : "Documentation Style Guide",
					"permalink" : "https:\/\/kubernetes.io\/docs\/home\/contribute\/style-guide\/"
					};
					(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
					</script>
					<a href="../style-guide.1" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
					'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
					
					
					
					<a href="../../../editdocs#docs/home/contribute/style-guide.md" class="button issue">Edit this Page</a>
					
				</div>
			</div>
		</section>
		<footer>
    <main class="light-text">
        <nav>
            
            
            
            <a href="../../../home.1">Documentation</a>
            
            <a href="../../../../blog/index.html">Blog</a>
            
            <a href="../../../../partners/index.html">Partners</a>
            
            <a href="../../../../community/index.html">Community</a>
            
            <a href="../../../../case-studies/index.html">Case Studies</a>
            
        </nav>
        <div class="social">
            <div>
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
            </div>
            <div>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
            <div>
                <a href="../../../getting-started-guides/index.html" class="button">Get Kubernetes</a>
                <a href="https://git.k8s.io/community/contributors/guide" class="button">Contribute</a>
            </div>
        </div>
        <div id="miceType" class="center">
            &copy; 2018 The Kubernetes Authors | Documentation Distributed under <a href="https://git.k8s.io/website/LICENSE" class="light-text">CC BY 4.0</a>
        </div>
        <div id="miceType" class="center">
            Copyright &copy; 2018 The Linux Foundation&reg;. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage" class="light-text">Trademark Usage page</a>
        </div>
    </main>
</footer>

		<button class="flyout-button" onclick="kub.toggleToc()"></button>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-36037335-10', 'auto');
ga('send', 'pageview');


(function () {
    window.addEventListener('DOMContentLoaded', init)

        
        function init() {
            window.removeEventListener('DOMContentLoaded', init)
                hideNav()
        }

    function hideNav(toc){
        if (!toc) toc = document.querySelector('#docsToc')
        if (!toc) return
            var container = toc.querySelector('.container')

                
                if (container) {
                    if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
                        toc.style.display = 'none'
                            document.getElementById('docsContent').style.width = '100%'
                    }
                } else {
                    requestAnimationFrame(function () {
                        hideNav(toc)
                    })
                }
    }
})();
</script>



	</body>
</html>